Autogenerated HTML docs for v2.33.0-113-g6c408
diff --git a/RelNotes/2.34.0.txt b/RelNotes/2.34.0.txt index cfbea48..e378a99 100644 --- a/RelNotes/2.34.0.txt +++ b/RelNotes/2.34.0.txt
@@ -10,6 +10,10 @@ location relative to Git installation (e.g. its $sharedir which is $(prefix)/share), with "%(prefix)". + * Use `ort` instead of `recursive` as the default merge strategy. + + * The userdiff pattern for "java" language has been updated. + Performance, Internal Implementation, Development Support etc. @@ -32,6 +36,14 @@ "git fetch-pack" has been optimized by taking advantage of the commit graph when available. + * Remind developers that the userdiff patterns should be kept simple + and permissive, assuming that the contents they apply are always + syntactically correct. + + * The current implementation of GIT_TEST_FAIL_PREREQS is broken in + that checking for the lack of a prerequisite would not work. Avoid + the use of "if ! test_have_prereq X" in a test script. + Fixes since v2.33 ----------------- @@ -44,5 +56,22 @@ push" code path. (merge 82823118b9 jt/push-negotiation-fixes later to maint). + * "git pull" had various corner cases that were not well thought out + around its --rebase backend, e.g. "git pull --ff-only" did not stop + but went ahead and rebased when the history on other side is not a + descendant of our history. The series tries to fix them up. + (merge 6f843a3355 en/pull-conflicting-options later to maint). + + * "git apply" miscounted the bytes and failed to read to the end of + binary hunks. + (merge 46d723ce57 jk/apply-binary-hunk-parsing-fix later to maint). + + * "git range-diff" code clean-up. + (merge c4d5907324 jk/range-diff-fixes later to maint). + * Other code cleanup, docfix, build fix, etc. (merge 1d9c8daef8 ab/bundle-doc later to maint). + (merge 81483fe613 en/merge-strategy-docs later to maint). + (merge 626beebdf8 js/log-protocol-version later to maint). + (merge 00e302da76 cb/builtin-merge-format-string-fix later to maint). + (merge ad51ae4dc0 cb/ci-freebsd-update later to maint).
diff --git a/git-merge.html b/git-merge.html index 15bf3b6..4cb631b 100644 --- a/git-merge.html +++ b/git-merge.html
@@ -998,8 +998,8 @@ Use the given merge strategy; can be supplied more than once to specify them in the order they should be tried. If there is no <code>-s</code> option, a built-in list of strategies - is used instead (<em>git merge-recursive</em> when merging a single - head, <em>git merge-octopus</em> otherwise). + is used instead (<code>ort</code> when merging a single head, + <code>octopus</code> otherwise). </p> </dd> <dt class="hdlist1"> @@ -1487,36 +1487,26 @@ arguments to <code>git merge</code> and/or <code>git pull</code>.</p></div> <div class="dlist"><dl> <dt class="hdlist1"> -resolve +ort </dt> <dd> <p> - This can only resolve two heads (i.e. the current branch - and another branch you pulled from) using a 3-way merge - algorithm. It tries to carefully detect criss-cross - merge ambiguities and is considered generally safe and - fast. + This is the default merge strategy when pulling or merging one + branch. This strategy can only resolve two heads using a + 3-way merge algorithm. When there is more than one common + ancestor that can be used for 3-way merge, it creates a merged + tree of the common ancestors and uses that as the reference + tree for the 3-way merge. This has been reported to result in + fewer merge conflicts without causing mismerges by tests done + on actual merge commits taken from Linux 2.6 kernel + development history. Additionally this strategy can detect + and handle merges involving renames. It does not make use of + detected copies. The name for this algorithm is an acronym + ("Ostensibly Recursive’s Twin") and came from the fact that it + was written as a replacement for the previous default + algorithm, <code>recursive</code>. </p> -</dd> -<dt class="hdlist1"> -recursive -</dt> -<dd> -<p> - This can only resolve two heads using a 3-way merge - algorithm. When there is more than one common - ancestor that can be used for 3-way merge, it creates a - merged tree of the common ancestors and uses that as - the reference tree for the 3-way merge. This has been - reported to result in fewer merge conflicts without - causing mismerges by tests done on actual merge commits - taken from Linux 2.6 kernel development history. - Additionally this can detect and handle merges involving - renames, but currently cannot make use of detected - copies. This is the default merge strategy when pulling - or merging one branch. -</p> -<div class="paragraph"><p>The <em>recursive</em> strategy can take the following options:</p></div> +<div class="paragraph"><p>The <em>ort</em> strategy can take the following options:</p></div> <div class="dlist"><dl> <dt class="hdlist1"> ours @@ -1542,29 +1532,6 @@ </p> </dd> <dt class="hdlist1"> -patience -</dt> -<dd> -<p> - With this option, <em>merge-recursive</em> spends a little extra time - to avoid mismerges that sometimes occur due to unimportant - matching lines (e.g., braces from distinct functions). Use - this when the branches to be merged have diverged wildly. - See also <a href="git-diff.html">git-diff(1)</a> <code>--patience</code>. -</p> -</dd> -<dt class="hdlist1"> -diff-algorithm=[patience|minimal|histogram|myers] -</dt> -<dd> -<p> - Tells <em>merge-recursive</em> to use a different diff algorithm, which - can help avoid mismerges that occur due to unimportant matching - lines (such as braces from distinct functions). See also - <a href="git-diff.html">git-diff(1)</a> <code>--diff-algorithm</code>. -</p> -</dd> -<dt class="hdlist1"> ignore-space-change </dt> <dt class="hdlist1"> @@ -1627,16 +1594,6 @@ </p> </dd> <dt class="hdlist1"> -no-renames -</dt> -<dd> -<p> - Turn off rename detection. This overrides the <code>merge.renames</code> - configuration variable. - See also <a href="git-diff.html">git-diff(1)</a> <code>--no-renames</code>. -</p> -</dd> -<dt class="hdlist1"> find-renames[=<n>] </dt> <dd> @@ -1670,6 +1627,72 @@ </dl></div> </dd> <dt class="hdlist1"> +recursive +</dt> +<dd> +<p> + This can only resolve two heads using a 3-way merge + algorithm. When there is more than one common + ancestor that can be used for 3-way merge, it creates a + merged tree of the common ancestors and uses that as + the reference tree for the 3-way merge. This has been + reported to result in fewer merge conflicts without + causing mismerges by tests done on actual merge commits + taken from Linux 2.6 kernel development history. + Additionally this can detect and handle merges involving + renames. It does not make use of detected copies. This was + the default strategy for resolving two heads from Git v0.99.9k + until v2.33.0. +</p> +<div class="paragraph"><p>The <em>recursive</em> strategy takes the same options as <em>ort</em>. However, +there are three additional options that <em>ort</em> ignores (not documented +above) that are potentially useful with the <em>recursive</em> strategy:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +patience +</dt> +<dd> +<p> + Deprecated synonym for <code>diff-algorithm=patience</code>. +</p> +</dd> +<dt class="hdlist1"> +diff-algorithm=[patience|minimal|histogram|myers] +</dt> +<dd> +<p> + Use a different diff algorithm while merging, which can help + avoid mismerges that occur due to unimportant matching lines + (such as braces from distinct functions). See also + <a href="git-diff.html">git-diff(1)</a> <code>--diff-algorithm</code>. Note that <code>ort</code> + specifically uses <code>diff-algorithm=histogram</code>, while <code>recursive</code> + defaults to the <code>diff.algorithm</code> config setting. +</p> +</dd> +<dt class="hdlist1"> +no-renames +</dt> +<dd> +<p> + Turn off rename detection. This overrides the <code>merge.renames</code> + configuration variable. + See also <a href="git-diff.html">git-diff(1)</a> <code>--no-renames</code>. +</p> +</dd> +</dl></div> +</dd> +<dt class="hdlist1"> +resolve +</dt> +<dd> +<p> + This can only resolve two heads (i.e. the current branch + and another branch you pulled from) using a 3-way merge + algorithm. It tries to carefully detect criss-cross + merge ambiguities. It does not handle renames. +</p> +</dd> +<dt class="hdlist1"> octopus </dt> <dd> @@ -1699,7 +1722,7 @@ </dt> <dd> <p> - This is a modified recursive strategy. When merging trees A and + This is a modified <code>ort</code> strategy. When merging trees A and B, if B corresponds to a subtree of A, B is first adjusted to match the tree structure of A, instead of reading the trees at the same level. This adjustment is also done to the common @@ -1707,7 +1730,7 @@ </p> </dd> </dl></div> -<div class="paragraph"><p>With the strategies that use 3-way merge (including the default, <em>recursive</em>), +<div class="paragraph"><p>With the strategies that use 3-way merge (including the default, <em>ort</em>), if a change is made on both branches, but later reverted on one of the branches, that change will be present in the merged result; some people find this behavior confusing. It occurs because only the heads and the merge base @@ -2154,7 +2177,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-05-08 15:24:24 PDT + 2021-08-30 16:49:46 PDT </div> </div> </body> diff --git a/git-merge.txt b/git-merge.txt index 3819fad..e4f3352 100644 --- a/git-merge.txt +++ b/git-merge.txt
@@ -61,6 +61,8 @@ OPTIONS ------- +:git-merge: 1 + include::merge-options.txt[] -m <msg>::
diff --git a/git-pull.html b/git-pull.html index f38e038..69d808f 100644 --- a/git-pull.html +++ b/git-pull.html
@@ -757,13 +757,16 @@ <div class="sect1"> <h2 id="_description">DESCRIPTION</h2> <div class="sectionbody"> -<div class="paragraph"><p>Incorporates changes from a remote repository into the current -branch. In its default mode, <code>git pull</code> is shorthand for -<code>git fetch</code> followed by <code>git merge FETCH_HEAD</code>.</p></div> -<div class="paragraph"><p>More precisely, <em>git pull</em> runs <em>git fetch</em> with the given -parameters and calls <em>git merge</em> to merge the retrieved branch -heads into the current branch. -With <code>--rebase</code>, it runs <em>git rebase</em> instead of <em>git merge</em>.</p></div> +<div class="paragraph"><p>Incorporates changes from a remote repository into the current branch. +If the current branch is behind the remote, then by default it will +fast-forward the current branch to match the remote. If the current +branch and the remote have diverged, the user needs to specify how to +reconcile the divergent branches with <code>--rebase</code> or <code>--no-rebase</code> (or +the corresponding configuration option in <code>pull.rebase</code>).</p></div> +<div class="paragraph"><p>More precisely, <code>git pull</code> runs <code>git fetch</code> with the given parameters +and then depending on configuration options or command line flags, +will call either <code>git rebase</code> or <code>git merge</code> to reconcile diverging +branches.</p></div> <div class="paragraph"><p><repository> should be the name of a remote repository as passed to <a href="git-fetch.html">git-fetch(1)</a>. <refspec> can name an arbitrary remote ref (for example, the name of a tag) or even @@ -861,6 +864,7 @@ <p> Perform the merge and commit the result. This option can be used to override --no-commit. + Only useful when merging. </p> <div class="paragraph"><p>With --no-commit perform the merge and stop just before creating a merge commit, to give the user a chance to inspect and further @@ -906,18 +910,26 @@ </p> </dd> <dt class="hdlist1"> +--ff-only +</dt> +<dd> +<p> + Only update to the new history if there is no divergent local + history. This is the default when no method for reconciling + divergent histories is provided (via the --rebase=* flags). +</p> +</dd> +<dt class="hdlist1"> --ff </dt> <dt class="hdlist1"> --no-ff </dt> -<dt class="hdlist1"> ---ff-only -</dt> <dd> <p> - Specifies how a merge is handled when the merged-in history is - already a descendant of the current history. <code>--ff</code> is the + When merging rather than rebasing, specifies how a merge is + handled when the merged-in history is already a descendant of + the current history. If merging is requested, <code>--ff</code> is the default unless merging an annotated (and possibly signed) tag that is not stored in its natural place in the <code>refs/tags/</code> hierarchy, in which case <code>--no-ff</code> is assumed. @@ -928,8 +940,6 @@ descendant of the current history), create a merge commit.</p></div> <div class="paragraph"><p>With <code>--no-ff</code>, create a merge commit in all cases, even when the merge could instead be resolved as a fast-forward.</p></div> -<div class="paragraph"><p>With <code>--ff-only</code>, resolve the merge as a fast-forward when possible. -When not possible, refuse to merge and exit with a non-zero status.</p></div> </dd> <dt class="hdlist1"> -S[<keyid>] @@ -960,6 +970,7 @@ In addition to branch names, populate the log message with one-line descriptions from at most <n> actual commits that are being merged. See also <a href="git-fmt-merge-msg.html">git-fmt-merge-msg(1)</a>. + Only useful when merging. </p> <div class="paragraph"><p>With --no-log do not list one-line descriptions from the actual commits being merged.</p></div> @@ -1022,6 +1033,7 @@ <div class="paragraph"><p>With --no-squash perform the merge and commit the result. This option can be used to override --squash.</p></div> <div class="paragraph"><p>With --squash, --commit is not allowed, and will fail.</p></div> +<div class="paragraph"><p>Only useful when merging.</p></div> </dd> <dt class="hdlist1"> --no-verify @@ -1030,6 +1042,7 @@ <p> This option bypasses the pre-merge and commit-msg hooks. See also <a href="githooks.html">githooks(5)</a>. + Only useful when merging. </p> </dd> <dt class="hdlist1"> @@ -1043,8 +1056,8 @@ Use the given merge strategy; can be supplied more than once to specify them in the order they should be tried. If there is no <code>-s</code> option, a built-in list of strategies - is used instead (<em>git merge-recursive</em> when merging a single - head, <em>git merge-octopus</em> otherwise). + is used instead (<code>ort</code> when merging a single head, + <code>octopus</code> otherwise). </p> </dd> <dt class="hdlist1"> @@ -1073,6 +1086,7 @@ a trusted key. If the tip commit of the side branch is not signed with a valid key, the merge is aborted. </p> +<div class="paragraph"><p>Only useful when merging.</p></div> </dd> <dt class="hdlist1"> --summary @@ -1114,6 +1128,7 @@ a very rare occasion, no configuration variable to enable this by default exists and will not be added. </p> +<div class="paragraph"><p>Only useful when merging.</p></div> </dd> <dt class="hdlist1"> -r @@ -1157,7 +1172,7 @@ </dt> <dd> <p> - Override earlier --rebase. + This is shorthand for --rebase=false. </p> </dd> </dl></div> @@ -1867,36 +1882,26 @@ arguments to <code>git merge</code> and/or <code>git pull</code>.</p></div> <div class="dlist"><dl> <dt class="hdlist1"> -resolve +ort </dt> <dd> <p> - This can only resolve two heads (i.e. the current branch - and another branch you pulled from) using a 3-way merge - algorithm. It tries to carefully detect criss-cross - merge ambiguities and is considered generally safe and - fast. + This is the default merge strategy when pulling or merging one + branch. This strategy can only resolve two heads using a + 3-way merge algorithm. When there is more than one common + ancestor that can be used for 3-way merge, it creates a merged + tree of the common ancestors and uses that as the reference + tree for the 3-way merge. This has been reported to result in + fewer merge conflicts without causing mismerges by tests done + on actual merge commits taken from Linux 2.6 kernel + development history. Additionally this strategy can detect + and handle merges involving renames. It does not make use of + detected copies. The name for this algorithm is an acronym + ("Ostensibly Recursive’s Twin") and came from the fact that it + was written as a replacement for the previous default + algorithm, <code>recursive</code>. </p> -</dd> -<dt class="hdlist1"> -recursive -</dt> -<dd> -<p> - This can only resolve two heads using a 3-way merge - algorithm. When there is more than one common - ancestor that can be used for 3-way merge, it creates a - merged tree of the common ancestors and uses that as - the reference tree for the 3-way merge. This has been - reported to result in fewer merge conflicts without - causing mismerges by tests done on actual merge commits - taken from Linux 2.6 kernel development history. - Additionally this can detect and handle merges involving - renames, but currently cannot make use of detected - copies. This is the default merge strategy when pulling - or merging one branch. -</p> -<div class="paragraph"><p>The <em>recursive</em> strategy can take the following options:</p></div> +<div class="paragraph"><p>The <em>ort</em> strategy can take the following options:</p></div> <div class="dlist"><dl> <dt class="hdlist1"> ours @@ -1922,29 +1927,6 @@ </p> </dd> <dt class="hdlist1"> -patience -</dt> -<dd> -<p> - With this option, <em>merge-recursive</em> spends a little extra time - to avoid mismerges that sometimes occur due to unimportant - matching lines (e.g., braces from distinct functions). Use - this when the branches to be merged have diverged wildly. - See also <a href="git-diff.html">git-diff(1)</a> <code>--patience</code>. -</p> -</dd> -<dt class="hdlist1"> -diff-algorithm=[patience|minimal|histogram|myers] -</dt> -<dd> -<p> - Tells <em>merge-recursive</em> to use a different diff algorithm, which - can help avoid mismerges that occur due to unimportant matching - lines (such as braces from distinct functions). See also - <a href="git-diff.html">git-diff(1)</a> <code>--diff-algorithm</code>. -</p> -</dd> -<dt class="hdlist1"> ignore-space-change </dt> <dt class="hdlist1"> @@ -2007,16 +1989,6 @@ </p> </dd> <dt class="hdlist1"> -no-renames -</dt> -<dd> -<p> - Turn off rename detection. This overrides the <code>merge.renames</code> - configuration variable. - See also <a href="git-diff.html">git-diff(1)</a> <code>--no-renames</code>. -</p> -</dd> -<dt class="hdlist1"> find-renames[=<n>] </dt> <dd> @@ -2050,6 +2022,72 @@ </dl></div> </dd> <dt class="hdlist1"> +recursive +</dt> +<dd> +<p> + This can only resolve two heads using a 3-way merge + algorithm. When there is more than one common + ancestor that can be used for 3-way merge, it creates a + merged tree of the common ancestors and uses that as + the reference tree for the 3-way merge. This has been + reported to result in fewer merge conflicts without + causing mismerges by tests done on actual merge commits + taken from Linux 2.6 kernel development history. + Additionally this can detect and handle merges involving + renames. It does not make use of detected copies. This was + the default strategy for resolving two heads from Git v0.99.9k + until v2.33.0. +</p> +<div class="paragraph"><p>The <em>recursive</em> strategy takes the same options as <em>ort</em>. However, +there are three additional options that <em>ort</em> ignores (not documented +above) that are potentially useful with the <em>recursive</em> strategy:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +patience +</dt> +<dd> +<p> + Deprecated synonym for <code>diff-algorithm=patience</code>. +</p> +</dd> +<dt class="hdlist1"> +diff-algorithm=[patience|minimal|histogram|myers] +</dt> +<dd> +<p> + Use a different diff algorithm while merging, which can help + avoid mismerges that occur due to unimportant matching lines + (such as braces from distinct functions). See also + <a href="git-diff.html">git-diff(1)</a> <code>--diff-algorithm</code>. Note that <code>ort</code> + specifically uses <code>diff-algorithm=histogram</code>, while <code>recursive</code> + defaults to the <code>diff.algorithm</code> config setting. +</p> +</dd> +<dt class="hdlist1"> +no-renames +</dt> +<dd> +<p> + Turn off rename detection. This overrides the <code>merge.renames</code> + configuration variable. + See also <a href="git-diff.html">git-diff(1)</a> <code>--no-renames</code>. +</p> +</dd> +</dl></div> +</dd> +<dt class="hdlist1"> +resolve +</dt> +<dd> +<p> + This can only resolve two heads (i.e. the current branch + and another branch you pulled from) using a 3-way merge + algorithm. It tries to carefully detect criss-cross + merge ambiguities. It does not handle renames. +</p> +</dd> +<dt class="hdlist1"> octopus </dt> <dd> @@ -2079,7 +2117,7 @@ </dt> <dd> <p> - This is a modified recursive strategy. When merging trees A and + This is a modified <code>ort</code> strategy. When merging trees A and B, if B corresponds to a subtree of A, B is first adjusted to match the tree structure of A, instead of reading the trees at the same level. This adjustment is also done to the common @@ -2087,7 +2125,7 @@ </p> </dd> </dl></div> -<div class="paragraph"><p>With the strategies that use 3-way merge (including the default, <em>recursive</em>), +<div class="paragraph"><p>With the strategies that use 3-way merge (including the default, <em>ort</em>), if a change is made on both branches, but later reverted on one of the branches, that change will be present in the merged result; some people find this behavior confusing. It occurs because only the heads and the merge base @@ -2264,7 +2302,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-02 15:41:53 PDT + 2021-08-30 16:49:46 PDT </div> </div> </body> diff --git a/git-pull.txt b/git-pull.txt index 7f4b2d1..aef757e 100644 --- a/git-pull.txt +++ b/git-pull.txt
@@ -15,14 +15,17 @@ DESCRIPTION ----------- -Incorporates changes from a remote repository into the current -branch. In its default mode, `git pull` is shorthand for -`git fetch` followed by `git merge FETCH_HEAD`. +Incorporates changes from a remote repository into the current branch. +If the current branch is behind the remote, then by default it will +fast-forward the current branch to match the remote. If the current +branch and the remote have diverged, the user needs to specify how to +reconcile the divergent branches with `--rebase` or `--no-rebase` (or +the corresponding configuration option in `pull.rebase`). -More precisely, 'git pull' runs 'git fetch' with the given -parameters and calls 'git merge' to merge the retrieved branch -heads into the current branch. -With `--rebase`, it runs 'git rebase' instead of 'git merge'. +More precisely, `git pull` runs `git fetch` with the given parameters +and then depending on configuration options or command line flags, +will call either `git rebase` or `git merge` to reconcile diverging +branches. <repository> should be the name of a remote repository as passed to linkgit:git-fetch[1]. <refspec> can name an @@ -132,7 +135,7 @@ unless you have read linkgit:git-rebase[1] carefully. --no-rebase:: - Override earlier --rebase. + This is shorthand for --rebase=false. Options related to fetching ~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/git-rebase.html b/git-rebase.html index 7220031..7e01202 100644 --- a/git-rebase.html +++ b/git-rebase.html
@@ -1140,9 +1140,7 @@ </dt> <dd> <p> - Use merging strategies to rebase. When the recursive (default) merge - strategy is used, this allows rebase to be aware of renames on the - upstream side. This is the default. + Using merging strategies to rebase (default). </p> <div class="paragraph"><p>Note that a rebase merge works by replaying each commit from the working branch on top of the <upstream> branch. Because of this, when a merge @@ -1159,9 +1157,8 @@ </dt> <dd> <p> - Use the given merge strategy. - If there is no <code>-s</code> option <em>git merge-recursive</em> is used - instead. This implies --merge. + Use the given merge strategy, instead of the default <code>ort</code>. + This implies <code>--merge</code>. </p> <div class="paragraph"><p>Because <em>git rebase</em> replays each commit from the working branch on top of the <upstream> branch using the given strategy, using @@ -1179,7 +1176,7 @@ <p> Pass the <strategy-option> through to the merge strategy. This implies <code>--merge</code> and, if no strategy has been - specified, <code>-s recursive</code>. Note the reversal of <em>ours</em> and + specified, <code>-s ort</code>. Note the reversal of <em>ours</em> and <em>theirs</em> as noted above for the <code>-m</code> option. </p> <div class="paragraph"><p>See also INCOMPATIBLE OPTIONS below.</p></div> @@ -1438,7 +1435,7 @@ <code>--preserve-merges</code> but works with interactive rebases, where commits can be reordered, inserted and dropped at will.</p></div> <div class="paragraph"><p>It is currently only possible to recreate the merge commits using the -<code>recursive</code> merge strategy; Different merge strategies can be used only via +<code>ort</code> merge strategy; different merge strategies can be used only via explicit <code>exec git merge -s <strategy> [...]</code> commands.</p></div> <div class="paragraph"><p>See also REBASING MERGES and INCOMPATIBLE OPTIONS below.</p></div> </dd> @@ -1865,36 +1862,26 @@ arguments to <code>git merge</code> and/or <code>git pull</code>.</p></div> <div class="dlist"><dl> <dt class="hdlist1"> -resolve +ort </dt> <dd> <p> - This can only resolve two heads (i.e. the current branch - and another branch you pulled from) using a 3-way merge - algorithm. It tries to carefully detect criss-cross - merge ambiguities and is considered generally safe and - fast. + This is the default merge strategy when pulling or merging one + branch. This strategy can only resolve two heads using a + 3-way merge algorithm. When there is more than one common + ancestor that can be used for 3-way merge, it creates a merged + tree of the common ancestors and uses that as the reference + tree for the 3-way merge. This has been reported to result in + fewer merge conflicts without causing mismerges by tests done + on actual merge commits taken from Linux 2.6 kernel + development history. Additionally this strategy can detect + and handle merges involving renames. It does not make use of + detected copies. The name for this algorithm is an acronym + ("Ostensibly Recursive’s Twin") and came from the fact that it + was written as a replacement for the previous default + algorithm, <code>recursive</code>. </p> -</dd> -<dt class="hdlist1"> -recursive -</dt> -<dd> -<p> - This can only resolve two heads using a 3-way merge - algorithm. When there is more than one common - ancestor that can be used for 3-way merge, it creates a - merged tree of the common ancestors and uses that as - the reference tree for the 3-way merge. This has been - reported to result in fewer merge conflicts without - causing mismerges by tests done on actual merge commits - taken from Linux 2.6 kernel development history. - Additionally this can detect and handle merges involving - renames, but currently cannot make use of detected - copies. This is the default merge strategy when pulling - or merging one branch. -</p> -<div class="paragraph"><p>The <em>recursive</em> strategy can take the following options:</p></div> +<div class="paragraph"><p>The <em>ort</em> strategy can take the following options:</p></div> <div class="dlist"><dl> <dt class="hdlist1"> ours @@ -1920,29 +1907,6 @@ </p> </dd> <dt class="hdlist1"> -patience -</dt> -<dd> -<p> - With this option, <em>merge-recursive</em> spends a little extra time - to avoid mismerges that sometimes occur due to unimportant - matching lines (e.g., braces from distinct functions). Use - this when the branches to be merged have diverged wildly. - See also <a href="git-diff.html">git-diff(1)</a> <code>--patience</code>. -</p> -</dd> -<dt class="hdlist1"> -diff-algorithm=[patience|minimal|histogram|myers] -</dt> -<dd> -<p> - Tells <em>merge-recursive</em> to use a different diff algorithm, which - can help avoid mismerges that occur due to unimportant matching - lines (such as braces from distinct functions). See also - <a href="git-diff.html">git-diff(1)</a> <code>--diff-algorithm</code>. -</p> -</dd> -<dt class="hdlist1"> ignore-space-change </dt> <dt class="hdlist1"> @@ -2005,16 +1969,6 @@ </p> </dd> <dt class="hdlist1"> -no-renames -</dt> -<dd> -<p> - Turn off rename detection. This overrides the <code>merge.renames</code> - configuration variable. - See also <a href="git-diff.html">git-diff(1)</a> <code>--no-renames</code>. -</p> -</dd> -<dt class="hdlist1"> find-renames[=<n>] </dt> <dd> @@ -2048,6 +2002,72 @@ </dl></div> </dd> <dt class="hdlist1"> +recursive +</dt> +<dd> +<p> + This can only resolve two heads using a 3-way merge + algorithm. When there is more than one common + ancestor that can be used for 3-way merge, it creates a + merged tree of the common ancestors and uses that as + the reference tree for the 3-way merge. This has been + reported to result in fewer merge conflicts without + causing mismerges by tests done on actual merge commits + taken from Linux 2.6 kernel development history. + Additionally this can detect and handle merges involving + renames. It does not make use of detected copies. This was + the default strategy for resolving two heads from Git v0.99.9k + until v2.33.0. +</p> +<div class="paragraph"><p>The <em>recursive</em> strategy takes the same options as <em>ort</em>. However, +there are three additional options that <em>ort</em> ignores (not documented +above) that are potentially useful with the <em>recursive</em> strategy:</p></div> +<div class="dlist"><dl> +<dt class="hdlist1"> +patience +</dt> +<dd> +<p> + Deprecated synonym for <code>diff-algorithm=patience</code>. +</p> +</dd> +<dt class="hdlist1"> +diff-algorithm=[patience|minimal|histogram|myers] +</dt> +<dd> +<p> + Use a different diff algorithm while merging, which can help + avoid mismerges that occur due to unimportant matching lines + (such as braces from distinct functions). See also + <a href="git-diff.html">git-diff(1)</a> <code>--diff-algorithm</code>. Note that <code>ort</code> + specifically uses <code>diff-algorithm=histogram</code>, while <code>recursive</code> + defaults to the <code>diff.algorithm</code> config setting. +</p> +</dd> +<dt class="hdlist1"> +no-renames +</dt> +<dd> +<p> + Turn off rename detection. This overrides the <code>merge.renames</code> + configuration variable. + See also <a href="git-diff.html">git-diff(1)</a> <code>--no-renames</code>. +</p> +</dd> +</dl></div> +</dd> +<dt class="hdlist1"> +resolve +</dt> +<dd> +<p> + This can only resolve two heads (i.e. the current branch + and another branch you pulled from) using a 3-way merge + algorithm. It tries to carefully detect criss-cross + merge ambiguities. It does not handle renames. +</p> +</dd> +<dt class="hdlist1"> octopus </dt> <dd> @@ -2077,7 +2097,7 @@ </dt> <dd> <p> - This is a modified recursive strategy. When merging trees A and + This is a modified <code>ort</code> strategy. When merging trees A and B, if B corresponds to a subtree of A, B is first adjusted to match the tree structure of A, instead of reading the trees at the same level. This adjustment is also done to the common @@ -2085,7 +2105,7 @@ </p> </dd> </dl></div> -<div class="paragraph"><p>With the strategies that use 3-way merge (including the default, <em>recursive</em>), +<div class="paragraph"><p>With the strategies that use 3-way merge (including the default, <em>ort</em>), if a change is made on both branches, but later reverted on one of the branches, that change will be present in the merged result; some people find this behavior confusing. It occurs because only the heads and the merge base @@ -2552,12 +2572,16 @@ successful merge so that the user can edit the message.</p></div> <div class="paragraph"><p>If a <code>merge</code> command fails for any reason other than merge conflicts (i.e. when the merge operation did not even start), it is rescheduled immediately.</p></div> -<div class="paragraph"><p>At this time, the <code>merge</code> command will <strong>always</strong> use the <code>recursive</code> -merge strategy for regular merges, and <code>octopus</code> for octopus merges, -with no way to choose a different one. To work around -this, an <code>exec</code> command can be used to call <code>git merge</code> explicitly, -using the fact that the labels are worktree-local refs (the ref -<code>refs/rewritten/onto</code> would correspond to the label <code>onto</code>, for example).</p></div> +<div class="paragraph"><p>By default, the <code>merge</code> command will use the <code>ort</code> merge strategy for +regular merges, and <code>octopus</code> for octopus merges. One can specify a +default strategy for all merges using the <code>--strategy</code> argument when +invoking rebase, or can override specific merges in the interactive +list of commands by using an <code>exec</code> command to call <code>git merge</code> +explicitly with a <code>--strategy</code> argument. Note that when calling <code>git +merge</code> explicitly like this, you can make use of the fact that the +labels are worktree-local refs (the ref <code>refs/rewritten/onto</code> would +correspond to the label <code>onto</code>, for example) in order to refer to the +branches you want to merge.</p></div> <div class="paragraph"><p>Note: the first command (<code>label onto</code>) labels the revision onto which the commits are rebased; The name <code>onto</code> is just a convention, as a nod to the <code>--onto</code> option.</p></div> @@ -2765,7 +2789,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-05-06 21:16:48 PDT + 2021-08-30 16:49:46 PDT </div> </div> </body> diff --git a/git-rebase.txt b/git-rebase.txt index 55af6fd..3f1030d 100644 --- a/git-rebase.txt +++ b/git-rebase.txt
@@ -340,9 +340,7 @@ -m:: --merge:: - Use merging strategies to rebase. When the recursive (default) merge - strategy is used, this allows rebase to be aware of renames on the - upstream side. This is the default. + Using merging strategies to rebase (default). + Note that a rebase merge works by replaying each commit from the working branch on top of the <upstream> branch. Because of this, when a merge @@ -354,9 +352,8 @@ -s <strategy>:: --strategy=<strategy>:: - Use the given merge strategy. - If there is no `-s` option 'git merge-recursive' is used - instead. This implies --merge. + Use the given merge strategy, instead of the default `ort`. + This implies `--merge`. + Because 'git rebase' replays each commit from the working branch on top of the <upstream> branch using the given strategy, using @@ -369,7 +366,7 @@ --strategy-option=<strategy-option>:: Pass the <strategy-option> through to the merge strategy. This implies `--merge` and, if no strategy has been - specified, `-s recursive`. Note the reversal of 'ours' and + specified, `-s ort`. Note the reversal of 'ours' and 'theirs' as noted above for the `-m` option. + See also INCOMPATIBLE OPTIONS below. @@ -530,7 +527,7 @@ where commits can be reordered, inserted and dropped at will. + It is currently only possible to recreate the merge commits using the -`recursive` merge strategy; Different merge strategies can be used only via +`ort` merge strategy; different merge strategies can be used only via explicit `exec git merge -s <strategy> [...]` commands. + See also REBASING MERGES and INCOMPATIBLE OPTIONS below. @@ -1219,12 +1216,16 @@ If a `merge` command fails for any reason other than merge conflicts (i.e. when the merge operation did not even start), it is rescheduled immediately. -At this time, the `merge` command will *always* use the `recursive` -merge strategy for regular merges, and `octopus` for octopus merges, -with no way to choose a different one. To work around -this, an `exec` command can be used to call `git merge` explicitly, -using the fact that the labels are worktree-local refs (the ref -`refs/rewritten/onto` would correspond to the label `onto`, for example). +By default, the `merge` command will use the `ort` merge strategy for +regular merges, and `octopus` for octopus merges. One can specify a +default strategy for all merges using the `--strategy` argument when +invoking rebase, or can override specific merges in the interactive +list of commands by using an `exec` command to call `git merge` +explicitly with a `--strategy` argument. Note that when calling `git +merge` explicitly like this, you can make use of the fact that the +labels are worktree-local refs (the ref `refs/rewritten/onto` would +correspond to the label `onto`, for example) in order to refer to the +branches you want to merge. Note: the first command (`label onto`) labels the revision onto which the commits are rebased; The name `onto` is just a convention, as a nod
diff --git a/gitfaq.html b/gitfaq.html index 90af707..dbe65c8 100644 --- a/gitfaq.html +++ b/gitfaq.html
@@ -1074,7 +1074,7 @@ </dt> <dd> <p> - By default, when Git does a merge, it uses a strategy called the recursive + By default, when Git does a merge, it uses a strategy called the <code>ort</code> strategy, which does a fancy three-way merge. In such a case, when Git performs the merge, it considers exactly three points: the two heads and a third point, called the <em>merge base</em>, which is usually the common ancestor of @@ -1262,7 +1262,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2020-09-29 14:47:55 PDT + 2021-08-30 16:49:46 PDT </div> </div> </body>
diff --git a/gitfaq.txt b/gitfaq.txt index afdaeab..8c1f2d5 100644 --- a/gitfaq.txt +++ b/gitfaq.txt
@@ -275,7 +275,7 @@ [[merge-two-revert-one]] If I make a change on two branches but revert it on one, why does the merge of those branches include the change?:: - By default, when Git does a merge, it uses a strategy called the recursive + By default, when Git does a merge, it uses a strategy called the `ort` strategy, which does a fancy three-way merge. In such a case, when Git performs the merge, it considers exactly three points: the two heads and a third point, called the _merge base_, which is usually the common ancestor of
diff --git a/howto/coordinate-embargoed-releases.html b/howto/coordinate-embargoed-releases.html index e60aa0f..801e686 100644 --- a/howto/coordinate-embargoed-releases.html +++ b/howto/coordinate-embargoed-releases.html
@@ -873,7 +873,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:43 PDT + 2021-08-30 16:51:19 PDT </div> </div> </body>
diff --git a/howto/keep-canonical-history-correct.html b/howto/keep-canonical-history-correct.html index 00bc40d..b33efef 100644 --- a/howto/keep-canonical-history-correct.html +++ b/howto/keep-canonical-history-correct.html
@@ -938,7 +938,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:43 PDT + 2021-08-30 16:51:19 PDT </div> </div> </body>
diff --git a/howto/maintain-git.html b/howto/maintain-git.html index e7f9468..828d0b8 100644 --- a/howto/maintain-git.html +++ b/howto/maintain-git.html
@@ -1469,7 +1469,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:43 PDT + 2021-08-30 16:51:19 PDT </div> </div> </body>
diff --git a/howto/new-command.html b/howto/new-command.html index 6edd7e0..dd7abac 100644 --- a/howto/new-command.html +++ b/howto/new-command.html
@@ -863,7 +863,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:39 PDT + 2021-08-30 16:51:12 PDT </div> </div> </body>
diff --git a/howto/rebase-from-internal-branch.html b/howto/rebase-from-internal-branch.html index ff8346e..dafb0dd 100644 --- a/howto/rebase-from-internal-branch.html +++ b/howto/rebase-from-internal-branch.html
@@ -895,7 +895,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:43 PDT + 2021-08-30 16:51:18 PDT </div> </div> </body>
diff --git a/howto/rebuild-from-update-hook.html b/howto/rebuild-from-update-hook.html index 1652a0b..483e2ac 100644 --- a/howto/rebuild-from-update-hook.html +++ b/howto/rebuild-from-update-hook.html
@@ -847,7 +847,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:43 PDT + 2021-08-30 16:51:18 PDT </div> </div> </body>
diff --git a/howto/recover-corrupted-blob-object.html b/howto/recover-corrupted-blob-object.html index 6b4c5d1..324716f 100644 --- a/howto/recover-corrupted-blob-object.html +++ b/howto/recover-corrupted-blob-object.html
@@ -880,7 +880,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:42 PDT + 2021-08-30 16:51:17 PDT </div> </div> </body>
diff --git a/howto/recover-corrupted-object-harder.html b/howto/recover-corrupted-object-harder.html index 48e78e3..54f7e5f 100644 --- a/howto/recover-corrupted-object-harder.html +++ b/howto/recover-corrupted-object-harder.html
@@ -1189,7 +1189,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:43 PDT + 2021-08-30 16:51:18 PDT </div> </div> </body>
diff --git a/howto/revert-a-faulty-merge.html b/howto/revert-a-faulty-merge.html index 6db49cc..46ff06d 100644 --- a/howto/revert-a-faulty-merge.html +++ b/howto/revert-a-faulty-merge.html
@@ -1025,7 +1025,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:42 PDT + 2021-08-30 16:51:16 PDT </div> </div> </body>
diff --git a/howto/revert-branch-rebase.html b/howto/revert-branch-rebase.html index a666ece..3960cc5 100644 --- a/howto/revert-branch-rebase.html +++ b/howto/revert-branch-rebase.html
@@ -907,7 +907,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:40 PDT + 2021-08-30 16:51:13 PDT </div> </div> </body>
diff --git a/howto/separating-topic-branches.html b/howto/separating-topic-branches.html index e01e563..741cce3 100644 --- a/howto/separating-topic-branches.html +++ b/howto/separating-topic-branches.html
@@ -841,7 +841,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:42 PDT + 2021-08-30 16:51:16 PDT </div> </div> </body>
diff --git a/howto/setup-git-server-over-http.html b/howto/setup-git-server-over-http.html index 62a0dcd..63f3679 100644 --- a/howto/setup-git-server-over-http.html +++ b/howto/setup-git-server-over-http.html
@@ -1071,7 +1071,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:41 PDT + 2021-08-30 16:51:15 PDT </div> </div> </body>
diff --git a/howto/update-hook-example.html b/howto/update-hook-example.html index 7a8c7a2..cc08163 100644 --- a/howto/update-hook-example.html +++ b/howto/update-hook-example.html
@@ -930,7 +930,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:41 PDT + 2021-08-30 16:51:15 PDT </div> </div> </body>
diff --git a/howto/use-git-daemon.html b/howto/use-git-daemon.html index 0f5234c..ddf367a 100644 --- a/howto/use-git-daemon.html +++ b/howto/use-git-daemon.html
@@ -791,7 +791,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:41 PDT + 2021-08-30 16:51:14 PDT </div> </div> </body>
diff --git a/howto/using-merge-subtree.html b/howto/using-merge-subtree.html index 984f60e..e2c5ff1 100644 --- a/howto/using-merge-subtree.html +++ b/howto/using-merge-subtree.html
@@ -848,7 +848,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:40 PDT + 2021-08-30 16:51:13 PDT </div> </div> </body>
diff --git a/howto/using-signed-tag-in-pull-request.html b/howto/using-signed-tag-in-pull-request.html index 68a1d7f..436f5e4 100644 --- a/howto/using-signed-tag-in-pull-request.html +++ b/howto/using-signed-tag-in-pull-request.html
@@ -952,7 +952,7 @@ <div id="footer"> <div id="footer-text"> Last updated - 2021-08-24 16:19:40 PDT + 2021-08-30 16:51:14 PDT </div> </div> </body>
diff --git a/merge-options.txt b/merge-options.txt index 5256501..61ec157 100644 --- a/merge-options.txt +++ b/merge-options.txt
@@ -2,6 +2,9 @@ --no-commit:: Perform the merge and commit the result. This option can be used to override --no-commit. +ifdef::git-pull[] + Only useful when merging. +endif::git-pull[] + With --no-commit perform the merge and stop just before creating a merge commit, to give the user a chance to inspect and further @@ -39,6 +42,7 @@ to `MERGE_MSG` before being passed on to the commit machinery in the case of a merge conflict. +ifdef::git-merge[] --ff:: --no-ff:: --ff-only:: @@ -47,6 +51,22 @@ default unless merging an annotated (and possibly signed) tag that is not stored in its natural place in the `refs/tags/` hierarchy, in which case `--no-ff` is assumed. +endif::git-merge[] +ifdef::git-pull[] +--ff-only:: + Only update to the new history if there is no divergent local + history. This is the default when no method for reconciling + divergent histories is provided (via the --rebase=* flags). + +--ff:: +--no-ff:: + When merging rather than rebasing, specifies how a merge is + handled when the merged-in history is already a descendant of + the current history. If merging is requested, `--ff` is the + default unless merging an annotated (and possibly signed) tag + that is not stored in its natural place in the `refs/tags/` + hierarchy, in which case `--no-ff` is assumed. +endif::git-pull[] + With `--ff`, when possible resolve the merge as a fast-forward (only update the branch pointer to match the merged branch; do not create a @@ -55,9 +75,11 @@ + With `--no-ff`, create a merge commit in all cases, even when the merge could instead be resolved as a fast-forward. +ifdef::git-merge[] + With `--ff-only`, resolve the merge as a fast-forward when possible. When not possible, refuse to merge and exit with a non-zero status. +endif::git-merge[] -S[<keyid>]:: --gpg-sign[=<keyid>]:: @@ -73,6 +95,9 @@ In addition to branch names, populate the log message with one-line descriptions from at most <n> actual commits that are being merged. See also linkgit:git-fmt-merge-msg[1]. +ifdef::git-pull[] + Only useful when merging. +endif::git-pull[] + With --no-log do not list one-line descriptions from the actual commits being merged. @@ -102,18 +127,25 @@ option can be used to override --squash. + With --squash, --commit is not allowed, and will fail. +ifdef::git-pull[] ++ +Only useful when merging. +endif::git-pull[] --no-verify:: This option bypasses the pre-merge and commit-msg hooks. See also linkgit:githooks[5]. +ifdef::git-pull[] + Only useful when merging. +endif::git-pull[] -s <strategy>:: --strategy=<strategy>:: Use the given merge strategy; can be supplied more than once to specify them in the order they should be tried. If there is no `-s` option, a built-in list of strategies - is used instead ('git merge-recursive' when merging a single - head, 'git merge-octopus' otherwise). + is used instead (`ort` when merging a single head, + `octopus` otherwise). -X <option>:: --strategy-option=<option>:: @@ -127,6 +159,10 @@ default trust model, this means the signing key has been signed by a trusted key. If the tip commit of the side branch is not signed with a valid key, the merge is aborted. +ifdef::git-pull[] ++ +Only useful when merging. +endif::git-pull[] --summary:: --no-summary:: @@ -167,3 +203,7 @@ projects that started their lives independently. As that is a very rare occasion, no configuration variable to enable this by default exists and will not be added. +ifdef::git-pull[] ++ +Only useful when merging. +endif::git-pull[] diff --git a/merge-strategies.txt b/merge-strategies.txt index 2912de7..5fc54ec 100644 --- a/merge-strategies.txt +++ b/merge-strategies.txt
@@ -6,28 +6,23 @@ can also take their own options, which can be passed by giving `-X<option>` arguments to `git merge` and/or `git pull`. -resolve:: - This can only resolve two heads (i.e. the current branch - and another branch you pulled from) using a 3-way merge - algorithm. It tries to carefully detect criss-cross - merge ambiguities and is considered generally safe and - fast. - -recursive:: - This can only resolve two heads using a 3-way merge - algorithm. When there is more than one common - ancestor that can be used for 3-way merge, it creates a - merged tree of the common ancestors and uses that as - the reference tree for the 3-way merge. This has been - reported to result in fewer merge conflicts without - causing mismerges by tests done on actual merge commits - taken from Linux 2.6 kernel development history. - Additionally this can detect and handle merges involving - renames, but currently cannot make use of detected - copies. This is the default merge strategy when pulling - or merging one branch. +ort:: + This is the default merge strategy when pulling or merging one + branch. This strategy can only resolve two heads using a + 3-way merge algorithm. When there is more than one common + ancestor that can be used for 3-way merge, it creates a merged + tree of the common ancestors and uses that as the reference + tree for the 3-way merge. This has been reported to result in + fewer merge conflicts without causing mismerges by tests done + on actual merge commits taken from Linux 2.6 kernel + development history. Additionally this strategy can detect + and handle merges involving renames. It does not make use of + detected copies. The name for this algorithm is an acronym + ("Ostensibly Recursive's Twin") and came from the fact that it + was written as a replacement for the previous default + algorithm, `recursive`. + -The 'recursive' strategy can take the following options: +The 'ort' strategy can take the following options: ours;; This option forces conflicting hunks to be auto-resolved cleanly by @@ -43,19 +38,6 @@ This is the opposite of 'ours'; note that, unlike 'ours', there is no 'theirs' merge strategy to confuse this merge option with. -patience;; - With this option, 'merge-recursive' spends a little extra time - to avoid mismerges that sometimes occur due to unimportant - matching lines (e.g., braces from distinct functions). Use - this when the branches to be merged have diverged wildly. - See also linkgit:git-diff[1] `--patience`. - -diff-algorithm=[patience|minimal|histogram|myers];; - Tells 'merge-recursive' to use a different diff algorithm, which - can help avoid mismerges that occur due to unimportant matching - lines (such as braces from distinct functions). See also - linkgit:git-diff[1] `--diff-algorithm`. - ignore-space-change;; ignore-all-space;; ignore-space-at-eol;; @@ -84,11 +66,6 @@ Disables the `renormalize` option. This overrides the `merge.renormalize` configuration variable. -no-renames;; - Turn off rename detection. This overrides the `merge.renames` - configuration variable. - See also linkgit:git-diff[1] `--no-renames`. - find-renames[=<n>];; Turn on rename detection, optionally setting the similarity threshold. This is the default. This overrides the @@ -105,6 +82,46 @@ is prefixed (or stripped from the beginning) to make the shape of two trees to match. +recursive:: + This can only resolve two heads using a 3-way merge + algorithm. When there is more than one common + ancestor that can be used for 3-way merge, it creates a + merged tree of the common ancestors and uses that as + the reference tree for the 3-way merge. This has been + reported to result in fewer merge conflicts without + causing mismerges by tests done on actual merge commits + taken from Linux 2.6 kernel development history. + Additionally this can detect and handle merges involving + renames. It does not make use of detected copies. This was + the default strategy for resolving two heads from Git v0.99.9k + until v2.33.0. ++ +The 'recursive' strategy takes the same options as 'ort'. However, +there are three additional options that 'ort' ignores (not documented +above) that are potentially useful with the 'recursive' strategy: + +patience;; + Deprecated synonym for `diff-algorithm=patience`. + +diff-algorithm=[patience|minimal|histogram|myers];; + Use a different diff algorithm while merging, which can help + avoid mismerges that occur due to unimportant matching lines + (such as braces from distinct functions). See also + linkgit:git-diff[1] `--diff-algorithm`. Note that `ort` + specifically uses `diff-algorithm=histogram`, while `recursive` + defaults to the `diff.algorithm` config setting. + +no-renames;; + Turn off rename detection. This overrides the `merge.renames` + configuration variable. + See also linkgit:git-diff[1] `--no-renames`. + +resolve:: + This can only resolve two heads (i.e. the current branch + and another branch you pulled from) using a 3-way merge + algorithm. It tries to carefully detect criss-cross + merge ambiguities. It does not handle renames. + octopus:: This resolves cases with more than two heads, but refuses to do a complex merge that needs manual resolution. It is @@ -121,13 +138,13 @@ the 'recursive' merge strategy. subtree:: - This is a modified recursive strategy. When merging trees A and + This is a modified `ort` strategy. When merging trees A and B, if B corresponds to a subtree of A, B is first adjusted to match the tree structure of A, instead of reading the trees at the same level. This adjustment is also done to the common ancestor tree. -With the strategies that use 3-way merge (including the default, 'recursive'), +With the strategies that use 3-way merge (including the default, 'ort'), if a change is made on both branches, but later reverted on one of the branches, that change will be present in the merged result; some people find this behavior confusing. It occurs because only the heads and the merge base diff --git a/technical/directory-rename-detection.txt b/technical/directory-rename-detection.txt index 49b83ef..029ee2c 100644 --- a/technical/directory-rename-detection.txt +++ b/technical/directory-rename-detection.txt
@@ -2,9 +2,9 @@ ========================== Rename detection logic in diffcore-rename that checks for renames of -individual files is aggregated and analyzed in merge-recursive for cases -where combinations of renames indicate that a full directory has been -renamed. +individual files is also aggregated there and then analyzed in either +merge-ort or merge-recursive for cases where combinations of renames +indicate that a full directory has been renamed. Scope of abilities ------------------ @@ -88,9 +88,11 @@ Folks have requested in the past that `git diff` detect directory renames and somehow simplify its output. It is not clear whether this would be desirable or how the output should be simplified, so this was - simply not implemented. Further, to implement this, directory rename - detection logic would need to move from merge-recursive to - diffcore-rename. + simply not implemented. Also, while diffcore-rename has most of the + logic for detecting directory renames, some of the logic is still found + within merge-ort and merge-recursive. Fully supporting directory + rename detection in diffs would require copying or moving the remaining + bits of logic to the diff machinery. * am
diff --git a/user-manual.html b/user-manual.html index 2a94272..d85de01 100644 --- a/user-manual.html +++ b/user-manual.html
@@ -1417,7 +1417,7 @@ bigger picture, you changed something else in that file and committed that <span class="strong"><strong>updated</strong></span> thing—the old state that you added originally ends up not being pointed to by any commit or tree, so it’s now a dangling blob -object.</p><p>Similarly, when the "recursive" merge strategy runs, and finds that +object.</p><p>Similarly, when the "ort" merge strategy runs, and finds that there are criss-cross merges and thus more than one merge base (which is fairly unusual, but it does happen), it will generate one temporary midway tree (or possibly even more, if you had lots of criss-crossing
diff --git a/user-manual.txt b/user-manual.txt index 9624059..865074b 100644 --- a/user-manual.txt +++ b/user-manual.txt
@@ -3190,7 +3190,7 @@ not being pointed to by any commit or tree, so it's now a dangling blob object. -Similarly, when the "recursive" merge strategy runs, and finds that +Similarly, when the "ort" merge strategy runs, and finds that there are criss-cross merges and thus more than one merge base (which is fairly unusual, but it does happen), it will generate one temporary midway tree (or possibly even more, if you had lots of criss-crossing
